Inside Macintosh: QuickTime Components /

Chapter 8 - Video Digitizer Components / Video Digitizer Components Reference

Video Digitizer Component Functions / Controlling Digitization

VDGrabOneFrameAsync

The VDGrabOneFrameAsync function instructs the video digitizer component to start to digitize asynchronously a single frame of source video. Because the component digitizes the video asynchronously, the application is free to do other things while
the digitization is performed.

pascal VideoDigitizerError VDGrabOneFrameAsync
                               (VideoDigitizerComponent ci,
                                 short buffer);

ci

Specifies the video digitizer component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.

buffer

Identifies the next output buffer. The value of this parameter must correspond to a valid index into the list of buffers that you supply when your application calls the VDSetupBuffers function (which is described on page 8-54). Note that this value is zero-based (that is, you must set this parameter to 0 to refer to the first buffer in the buffer list).

The video digitizer component uses this buffer for the next video frame (that is, the frame that will be digitized the next time the application calls the VDGrabOneFrameAsync function). In this manner, video digitizer components can quickly and efficiently prepare for the next video frame.

Some digitizer components may not allow your application to queue more than one asynchronous frame grab at a time. These components may not return control to your application until a previously requested grab has been completed.

DESCRIPTION

Applications determine when the digitizer component is finished with a frame by calling the VDDone function, which is described in the next section.

When calling the VDGrabOneFrameAsync function, the application specifies the next destination video buffer, allowing the digitizer component to quickly switch from the current buffer to the next buffer. In this manner, your application's ability to grab video at high frame rates is enhanced. See "Multiple Buffering" on page 8-8 for a discussion of multiple-buffered video digitization.

Applications can determine whether a video digitizer component supports asynchronous frame grabbing by examining the output capability flags of the digitizer component. Specifically, if the digiOutDoesAsyncGrabs flag is set to 1, the
digitizer component supports the VDGrabOneFrameAsync function and the VDDone function, which is described in the next section.

Applications can use the VDGetCurrentFlags function (described on page 8-25) to retrieve the digitizer component's output capability flags. If a video digitizer component does not support asynchronous digitization, applications must use the VDGrabOneFrame function (described on page 8-54) to perform single-frame digitization.

If the specified digitizer component is already digitizing continuously when the application calls VDGrabOneFrameAsync, the digitizer component returns the
next digitized frame and then stops. If the digitizer component is stopped, the component digitizes a single frame and then stops. To resume continuous digitization, applications should call the VDSetPlayThruOnOff function, which is described on page 8-53.

The VDGrabOneFrameAsync function also allows applications to use more than
one destination buffer for the digitized video. The application defines these buffers
by calling the VDSetupBuffers function (described on page 8-54). The application specifies one of these destination buffers for the digitized frame when it calls
the VDSetPlayThruDestination function (described on page 8-35) or the VDSetPlayThruGlobalRect function (described on page 8-39).

RESULT CODES

noErr	0	No error
digiUnimpErr	-2201	Function not supported

Main | Top of Section | What's New | Apple Computer, Inc. | Find It | Feedback | Help